<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
        <title>M3Gen :: Builders</title>
        <link rel="stylesheet" href="css/m3gen.css" type="text/css" />
    </head>
    <body>
    	<div id="content">
        <h1>M3Gen :: Terms and definitions</h1>
        <p>
            <!-- definition list -->
            <dl>
                <dt>
                    m3gen
                </dt>
                <dd>
                    Model Tree Generator (A generator that can build a specific tree model from any hierarchical model) 
					By default m3gen has been designed for generating a jsTree data model to draw the tree.
                </dd>
                <dt>
                    m3gen.Configuration
                </dt>
                <dd>
                    The Configuration module is used for global configurations of m3gen.
					Currently (v.0.1) defines settings/configurations for event handling, logging and pathSelector methods.
                </dd>
                <dt>
                    m3gen.Setup
                </dt>
                <dd>
                    The Setup module is used for setting up global m3gen namespaces and constants.
                </dd>
                <dt>
                    Base_functions
                </dt>
                <dd>
                    m3gen specific module of utility functions, shared (inherited) by all m3gen components.
                </dd>
                <dt>
                    Language_functions
                </dt>
                <dd>
                    m3gen specific module of language data related utility functions, part of Base_functions.
                </dd>																							
                <dt>
                    ruleSetConfiguration
                </dt>
                <dd>
                    A configuration of global rules (default rules) and specific ruleSets for each type of object that can be encountered in the json object structure.
					A ruleSetConfiguration can be composed (a merge of) multiple ruleSetConfigurations. 
                </dd>
                <dt>
                    ruleSet
                </dt>
                <dd>
                    A set of rules that describe/define how to handle a specific kind of json object and thus how to convert it into its final state as a jsTree node. 
                </dd>
                <dt>
                    pathSelector
                </dt>
                <dd>
                    A selector using a path based syntax to define which objects in hierarchical structure should be selected.
					A pathSelector is used by a pathMethod (function that understands and can use the given path syntax) to select the objects.
                </dd>
                <dt>
                    selectorFunction
                </dt>
                <dd>
                    A function that is applied on the json object structure directly to traverse and select objects.
                </dd>
                <dt>
                    resolvedContent
                </dt>
                <dd>
                    Content that has been resolved from a json object using the JsonObjParser.
					<code>
						{
								branch: false,
								id: id, 
								unique_id: uniqueId,
								attributes: attributes, 
								state: state, 
								title: title,
								icon: icon,
								languageData: languageData
						};						
					</code>
                </dd>				
				
				
                <dt>
                    nodeObj
                </dt>
                <dd>
                    An intermediary node containing enough info to create a jsTree node but also usable for transformation
					into other models for use by other consumers than the jsTree widget.
					<code>
					{id: "abc", unique_id: "abc_0", attributes: {...},
					 icon: "..", title: "...",					
					 languageData: {"dk": {title: "...", icon: "...", attributes: {...}}, en: {...}}, state: "closed", metaData: {...}}
					 </code>										
                </dd>
                <dt>
                    branchNodeObj
                </dt>
                <dd>
                    An nodeObj with children, which is an array of more nodeObj (resulting in a Composite structure).
					<code>
					{id: "abc", unique_id: "abc_0", attributes: {...},
					 icon: "..", title: "...",					
					 languageData: {...}, state: "closed", metaData: {...}, children: [nodeObj1, nodeObj2, ...]}
					 </code>					
                </dd>				
                <dt>
                    jsTreeNode
                </dt>
                <dd>
                	An object used by jsTree to create a tree node in the tree UI widget (a branch or a leaf).
					<code>
					{attributes: {id: "abc", rel: "..." }, data: {"dk": {title: "...", icon: "...", attributes: {...}}, en: {...}}, mdata: {...}}					
					</code>
					Note: For a jsTreeNode without children, the 'state' property is irrelevant.
                </dd>				
                <dt>
                    branchJsTreeNode
                </dt>
                <dd>
                	A jsTreeNode with children, which is an array of more jsTreeNode (resulting in a Composite structure).
					<code>
					{attributes: {id: "abc", rel: "..." }, data: {...}, state: "closed", mdata: {...}, children: [jsTreeNode1, jsTreeNode2, ...]}					
					</code> 
					Note: The 'state' property is only relevant for a branchJsTreeNode, since it indicates whether the children should be shown in the widget or initially hidden, 
					requiring some action to open the branch and display the children.                   
                </dd>
                <dt>
                    objTypeCounter
                </dt>
                <dd>
                	A counter used for a paticular kind of objType encountered. Each time a json object of this particular objType is encountered, the matching objTypeCounter
					is increased. The objTypeCounter is used for counting how many objects of each type have been encountered and is also used to generate unique id for the resulting nodes
					in case useUniqueId is set to true.
                </dd>
                <dt>
                    json contentSelectionFunction
                </dt>
                <dd>
                	A functions within a ruleSet (such as selectId, selectTitle etc.). 
					These functions are used to select a specific content part of a json object being parsed. 
                </dd>	
                <dt>
                    branch contentSelectionFunction (v.0.2)
                </dt>
                <dd>
					For branches, it makes sense that the childSelector, either function or string is used as the key
					to a ruleSet for the branch. The arguments passed to each branch contentSelectFunction should be:
					jsonObj (where branch is to be attached), resolvedContent (of jsonObj where branch is to be attached), 
					children, branchType, branchDefinition.	                
				</dd>																																				
			</dl>							
        </p>
		<p>
			<h2>RuleSetConfiguration terms</h2>
			<dl>
               <dt>
                    useUniqueId
                </dt>
                <dd>
                	Global default flag used to used in case no useUniqueId could be determined using the active ruleSet.
					Indicate whether a unique id should be generated and used for a given jsTree node.
					If false an id is generated using the selectId function of the active ruleSet.
					If true m3gen attempts go generate a uniqueId (by default using an objTypeCounter), appending a running number to the identifier string.
					<code>
					useUniqueId: true|false (boolean)
					</code> 
                </dd>
               <dt>
                    defaultState
                </dt>
                <dd>
                	Global default branch state used in case no state could be determined using the active ruleSet
					<code>
					defaultState: 'open'|'closed' 
					</code> 
                </dd>
               <dt>
                    ruleSetsDisabled
                </dt>
                <dd>
                	Global setting (array) to disable one or more ruleSets. 
					Overrides any matching ruleSet name in ruleSetsEnabled.
					If empty, no ruleSets are disabled, except those left out of any non-empty ruleSetsEnabled.
					<code>
					ruleSetsDisabled: ['badPerson', 'evilPerson'] 
					</code> 
                </dd>				
           		<dt>
                    ruleSetsEnabled
                </dt>
                <dd>
                	Global setting (array) to specifically enable one or more ruleSets.
					If empty, all ruleSets are enabled, otherwise only those listed are enabled.
					<code>
					ruleSetsEnabled: ['goodPerson'] 
					</code> 
                </dd>				
           		<dt>
                    iconsPath
                </dt>
                <dd>
                	Global setting to specify the base path used for icons.
					<code>
					iconsPath: 'icons/tree/' 
					</code> 
                </dd>
           		<dt>
                    branchTypeRules
                </dt>
                <dd>
                	Set of branchTypeRule
					<code>
					iconsPath: 'icons/tree/' 
					</code> 
                </dd>				
				
								
           		<dt>
                    branchTypeRule
                </dt>
                <dd>
                	Defines the content rules for a specific type of branch. 
					A valid branchDefinition always has branchType key with a string identifier matchin a key in branchTypeRules, 
					which is the branchTypeRule to be used for this branch.
					<code>
					'folder': {
						data: {
							en: {
								icon: 'folder_en.png'
							},
							dk: {
								icon: 'folder_dk.png'
							},
							'default': {
								icon: 'folder.png'
							}
						},            
			            state: 'closed'
			        }									
					</code> 
					TODO: Not sure 'data' is a good key, perhaps better to use languageData?
                </dd>				
           		<dt>
                    pathMethod
                </dt>
                <dd>
                	Global setting to define the default kind of path method used (for resolving children).
					By default xpath (syntax: 'x/y/z') and jpath (syntax: 'x.y.z') are supported.
					<code>
					pathMethod: 'jpath' 
					</code> 
					Mappings for pathMethods are defined in m3gen.pathFinderSettings in m3gen.Configuration.js
                </dd>	
           		<dt>
                    ruleSets
                </dt>
                <dd>
                	A collection of ruleSet
					<code>
					ruleSets: {
						person: {...}, company: {...}, ...
					}
					</code> 					
                </dd>							
           		<dt>
                    ruleSet (v.0.2 : nodeRuleSet)
                </dt>
                <dd>
                	An object containing rules for how to handle a specific kind of json object and convert it into content that can
					be used for creating a tree node.
				<code>
				  	'person': { 
							  functions: personSelectFunctions,					
						 	  branchTypeRules: {'folder': {icon: 'folder.png', state: 'closed'}},

							  childBranches:[{branchNode: {id: 'boys', title:'My boys', branchType: 'folder'}, selectors: ['myChildren.boys', personSelectFunctions.boy18Selector]}, 
							  			  {branchNode: {id: 'girls', title:' My girls', state: 'open', branchType: 'folder'}, selectors: ['myChildren.girls', personSelectFunctions.selectFriends]}
							  ],

							  refBranches:[{
							  		branchNode: {title:'My siblings', state: 'closed', branchType: 'folder'}, 
							  		selectors: ['siblings']
							  }],

							  iconsPath : 'images/person'
							  defaultState: 'closed', 
							  useUniqueId: true,							  
					} 			  
				</code>					
				TODO: functions should be renamed contentSelectors (v.0.2)	
                </dd>	
           		<dt>
                    branchRuleSet (v.0.2)
                </dt>
                <dd>
                	An object containing rules for how to handle a specific kind of branch object.
				<code>
				  	'myChildren.boys': { 
							  functions: personSelectFunctions,
							  branchTypeRules: {...}, // override
							  branchDefinition: {...}, // override					
							  iconsPath : 'images/person', // override 
							  defaultState: 'closed', // override
							  useUniqueId: true, // override							  
					} 			  
				</code>					
				TODO: functions should be renamed contentSelectors (v.0.2)	
                </dd>																													
			</dl>						
		</p>
		<p>
			<h2>RuleSet terms</h2>
			<dl>
               <dt>
                    functions (v.0.2: nodeContentSelectors and branchContentSelectors)
                </dt>
				<dd>		
					Contains a set of jsonContentSelectors and branchContentSelectors
					<code>
						contentSelectors: {
							node: {..}
							branch: {..}
						}						
					</code>
                </dd>	
               <dt>
                    childBranches
                </dt>
				<dd>		
					Rules for resolving child branches, including childSelectors and branchDefinitions.
					The nodes resolved using these rules become instances, unless such instances are 
					duplicates, in which case they become references to the first such instance encountered previuosly.
                </dd>				
                <dt>
                    refBranches
                </dt>
				<dd>		
					Rules for resolving child branches, including childSelectors and branchDefinitions.
					The nodes resolved using these rules always become childless references.
                </dd>
                <dt>
                    branchTypeRules
                </dt>
				<dd>		
					RuleSet override of branchTypeRules in ruleSetConfiguration
                </dd>					
                <dt>
                    iconsPath
                </dt>
				<dd>		
					RuleSet override of iconsPath in ruleSetConfiguration
                </dd>	
                <dt>
                    defaultState
                </dt>
				<dd>		
					RuleSet override of defaultState in ruleSetConfiguration
                </dd>	
                <dt>
                    useUniqueId
                </dt>
				<dd>		
					RuleSet override of useUniqueId in ruleSetConfiguration
                </dd>	
				<dt>
					branchRules
				</dt>	
				<dd>
					Set of branchRule that define how to generate branches to hold specific sets of child nodes.
					<code>
					    branchRules: [
							{
					        	branchDef: {... },
					        	selectors: ['myChildren.boys']
					    	}, 						
							{branchDef: {...}, selectors: [...]}
						]							
					</code>
				</dd>	
				<dt>
					branchRule
				</dt>	
				<dd>
					Set of branchRule that define how to generate branches to hold specific sets of child nodes.
					<code>
						branchRule_boys = {
					        branchDef: {
					            id: 'boys',
					            data: {
									en: {
										title: 'My boys'
									},
									dk: {
										title: 'Mine drenge'
									}
								},				
					            branchType: 'folder'
					        },
					        selectors: ['myChildren.boys']
					    }							
					</code>
				</dd>
				<dt>
					branchDefinition
				</dt>	
				<dd>
					A simple content definition for the creation of a branch to hold children found when resolving
					the branchRule. A branchDefinition is always connected to a branchRule.
					The id string identifier is added to the id of the node containing the branch 
					and adding a running counter number (from a branchTypeCounter).
					<h3>Example</h3>
					For a node that resolves to id='person_Jack_1', a 'boys' branchNode is created.
					This branchNode is given an id = 'person_Jack_1_boys'. To be sure a unique ID is generated,
					a counter, branchTypeCounter['boys'] is used (=0), to create a final id='person_Jack_1_boys_0'.
					<code>
				        branchDefinition_boys = {
				            id: 'boys',
				            data: {
								en: {
									title: 'My boys'
								},
								dk: {
									title: 'Mine drenge'
								}
							},				
				            branchType: 'folder'
				        }				
					</code>
					TODO: 
					'selectors' to be renamed 'childrenSelectors' (v.0.2).
					'data' to be renamed 'languageData' (v.0.2)	
					Use branchTypeCounter to ensure uniqueness (v.0.2)	 			
				</dd>				
				<dt>
					branchChildrenSelectors
				</dt>	
				<dd>
					Set of childrenSelector to find children within the json structure for the current node.
					Each childrenSelector can be either a path in string format, resolved by a pathMethod handler (function)
					or a function that traverses the json structure on its own. Using a path string is the quick and easy way, but 
					using a function allows for more flexibility, fx using some kind of 'business rules' to determine which children to include/exclude.
					<code>
						branchRule_boys = {
					        branchDef: {
					            id: 'boys',
					            data: {
									en: {
										title: 'My boys'
									},
									dk: {
										title: 'Mine drenge'
									}
								},				
					            branchType: 'folder'
					        },
					        selectors: ['myChildren.boys']
					    }							
					</code>
					TODO: 
					'selectors' to be renamed 'childrenSelectors' (v.0.2).
					'data' to be renamed 'languageData' (v.0.2)					
				</dd>																																																				
			</dl>						
		</p>	
		<p>
			<h2>contentSelector terms</h2>
			<dl>
               <dt>
                    nodeContentSelectorFunctions (v.0.2)
                </dt>
				<dd>
					<code>
						node: {
							options: {..}
							selectorFunctions: {
								selectId: function(...) {},
								selectTitle: function(...) {},
							}
						}						
					</code>						
                </dd>
               	<dt>
                    branchContentSelectorFunctions (v.0.2)
                </dt>
				<dd>
					<code>
						branch: {
							options: {..}
							selectorFunctions: {
								selectId: function(...) {},
								selectTitle: function(...) {},
							}
						}						
					</code>							
                </dd>											
               	<dt>
                    childrenSelectorFunctions (v.0.2)
                </dt>
				<dd>
					Functions used to select children, instead of using pathChildSelectors.	
					<code>
						children: {
							options: {..}
							selectorFunctions: {
								selectId: function(...) {},
								selectTitle: function(...) {},
							}
						}						
					</code>						
                </dd>																																								
			</dl>						
		</p>									
		<p>
			<h1>M3Gen Components</h1>
			<h2>Main Generator</h2>
			<dl>		
                <dt>
                    JsTreeModelGenerator
                </dt>
                <dd>
                    The main jsTree model generator that can generate a jsTree model from a json object structure using a ruleSetConfiguration.
                </dd>
			</dl>		
		<p>
			<h2>Parsers</h2>
			<dl>
                <dt>
                    JsonObjParser
                </dt>
                <dd>
                    A Parser used by the JsTreeModelGenerator to parse a json object and resolve it into resolvedContent, used to create a nodeObj. 
					
                </dd>				
                <dt>
                    JsonObjParserLang
                </dt>
                <dd>
                    A set of parser functions that are part of JsonObjParser, used to resolve language related content (for multi-language support).
                </dd>
                <dt>
                    ChildrenParser
                </dt>
                <dd>
                    A Parser used by JsonObjParser to parse children of a json object within that same json object structure (using path selectors or selector functions)
                </dd>								
			</dl>							
        </p>						
		<p>
			<h2>Builders</h2>
			<dl>
                <dt>
                    JsTreeNodeContentBuilders
                </dt>
                <dd>
                    A set of Builders used to construct the internals of a jsTree node
					
                </dd>				
                <dt>
                    AttributesBuilder
                </dt>
                <dd>
                    A Builder used to construct the 'attributes' object of a jsTree node
                </dd>
                <dt>
                    DataBuilder
                </dt>
                <dd>
                    A Builder used to construct the 'data' object of a jsTree node
                </dd>
                <dt>
                    StateBuilder
                </dt>
                <dd>
                    A Builder used to construct the 'state' object of a jsTree node
                </dd>
                <dt>
                    MetaDataBuilder
                </dt>
                <dd>
                    A Builder used to construct the 'mdata' object of a jsTree node
                </dd>				
				
                <dt>
                    NodeObjBuilder
                </dt>
                <dd>
                    A Builder class to build a NodeObj
                </dd>
                <dt>
                    NodeObjBranchBuilder
                </dt>
                <dd>
                    A Builder class to build a special branch NodeObj (a NodeObj that can contain other NodeObj)
					 Note that any icon/title within languageData should normally be treated as having higher precedence than the non-language title/icon
                </dd>	
                <dt>
                    JsTreeNodeBuilder
                </dt>
                <dd>
                    A Builder class to build a jsTree node
					Note that any language attribute has higher precedence than a matching attribute in "non-language" attributes.
                </dd>							
            </dl>			
		</p>
		</div>
    </body>
</html>
